<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Xinc Guide - Getting Started</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
    <link rel="Stylesheet" rev="Stylesheet" href="../css/Documentation.css" type="text/css" media="All" charset="iso-8859-1" />
</head>
<body>

<h1><a name="GettingStarted"></a>Getting Started</h1>

<p> Xinc buildfiles are written in XML, and so you will need to know at least
  some basic things about XML to understand the following chapter. There is a
  lot of information available on the web: </p>

<ul>
  <li>The Standard Recommendation of XML by the w3c
     <a href="http://www.w3.org/TR/2000/REC-xml">http://www.w3.org/TR/2000/REC-xml</a>:
     very technical but exhaustive.</li>
  <li><em>XML In 10 Points</em>
     <a href="http://www.w3.org/XML/1999/XML-in-10-points">http://www.w3.org/XML/1999/XML-in-10-points</a>:
     Quick introduction into XML.</li>
  <li><em>A technical introduction to XML</em>
      <a href="http://www.xml.com/pub/a/98/10/guide0.html">http://www.xml.com/pub/a/98/10/guide0.html</a>:
      Interesting article by the creator of DocBook.
      </li>
</ul>

<h2><a name="XMLAndXinc"></a>XML And Xinc</h2>

<p>A valid Xinc buildfile has the following basic structure:</p>


<ul>
  <li>The document prolog</li>
  <li>Exactly one root element called <em>&lt;xinc/&gt;</em> .</li>
  <li>One to many elements called <em>&lt;project/&gt;</em> .</li>
  <li>Each project element has several Xinc <em>type</em> elements (i.e. <em>&lt;property/&gt;</em> , <em>&lt;modificationset/&gt;</em>
    , <em>&lt;builders/&gt;</em>, <em>&lt;publishers/&gt;</em> etc.)</li>
  <li>Each of the project elements might have children elements (i.e. <em>&lt;builders&gt;&lt;phingbuilder/&gt;&lt;/builders&gt;</em>,
</ul>

<h2><a name="SettingUpASimpleProject"></a>Setting up a simple project</h2>

<p>We are going to setup the following sample project:</p>

<table>
  <caption>
  MyFirstXincProject 
  </caption>
  <tbody>
    <tr>
      <td><strong>name</strong></td>
      <td>MyFirstXincProject</td>
    </tr>
    <tr>
      <td><strong>svn repository</strong></td>
      <td>svn://svn.example.com/trunk</td>
    </tr>
    <tr>
      <td><strong>project directory</strong></td>
      <td>/var/xinc/projects/MyFirstXincProject</td>
    </tr>
  </tbody>
</table>
<h3>Creating the Project Structure</h3>
<ol>
<li>$ mkdir /var/xinc/projects/MyFirstXincProject<i style="margin-left:30px">(creating the project directory)</i></li>
<li>$ cd /var/xinc/projects/MyFirstXincProject<i style="margin-left:30px">(change workingdir to project dir)</i></li>
<li>$ svn co svn://svn.example.com/trunk .<i style="margin-left:30px">(checking out a working copy from subversion repos)</i></li>
</ol>

<h3>Configuring the project in Xinc</h3>
<p>Create a Xinc project file in /etc/xinc/conf.d/MyFirstXincProject.xml with the following content:</p>
<pre title="Example of a simple project file">
<strong>01</strong> &lt;?xml version=&quot;1.0&quot;?&gt;
<strong>02</strong> &lt;xinc engine=&quot;Sunrise&quot;&gt;
<strong>02</strong>     &lt;<a href="appendixes/AppendixB-CoreTasks.html#Project">project</a> name=&quot;MyFirstXincProject&quot;&gt;
<strong>03</strong>         &lt;<a href="appendixes/AppendixB-CoreTasks.html#PropertyTask">property</a> name=&quot;dir&quot; value=&quot;${projectdir}/${project.name}&quot; /&gt;
<strong>04</strong>         &lt;<a href="appendixes/AppendixB-CoreTasks.html#ScheduleTask">schedule</a> interval=&quot;240&quot; /&gt;
<strong>05</strong>         &lt;<a href="appendixes/AppendixB-CoreTasks.html#ModificationSetTask">modificationset</a>&gt;
<strong>06</strong>             &lt;<a href="appendixes/AppendixC-ModificationSet.html#SvnTask">svn</a> directory=&quot;${dir}&quot; update=&quot;true&quot; /&gt;
<strong>07</strong>         &lt;/modificationset&gt;
<strong>08</strong>         &lt;<a href="appendixes/AppendixB-CoreTasks.html#BuildersTask">builders</a>&gt;
<strong>09</strong>             &lt;<a href="appendixes/AppendixD-Builders.html#PhingbuilderTask">phingbuilder</a> buildfile=&quot;${dir}/build.xml&quot; /&gt;
<strong>10</strong>         &lt;/builders&gt;
<strong>11</strong>         &lt;<a href="appendixes/AppendixB-CoreTasks.html#PublishersTask">publishers</a>&gt;
<strong>12</strong>             &lt;<a href="appendixes/AppendixE-Publishers.html#OnfailureTask">onfailure</a>&gt;
<strong>13</strong>                 &lt;<a href="appendixes/AppendixE-Publishers.html#EmailTask">email</a> to=&quot;you@email.com&quot; subject=&quot;Build failed&quot;
<strong>14</strong>                     message=&quot;Build of project failed&quot; /&gt;
<strong>15</strong>             &lt;/onfailure&gt;
<strong>16</strong>             &lt;<a href="appendixes/AppendixE-Publishers.html#OnsuccessTask">onsuccess</a>&gt;
<strong>17</strong>                 &lt;<a href="appendixes/AppendixE-Publishers.html#EmailTask">email</a> to=&quot;you@email.com&quot; subject=&quot;Build success&quot;
<strong>18</strong>                     message=&quot;Build of project was successful&quot; /&gt;
<strong>19</strong>             &lt;/onsuccess&gt;
<strong>20</strong>         &lt;/publishers&gt;
<strong>21</strong>     &lt;/project&gt;
<strong>22</strong> &lt;/xinc&gt;
</pre>

<ul>
<li><strong>Line 03:</strong><br/>Defines a property named "dir" which can be used in the whole configuration using "${dir}"</li>
<li><strong>Line 04:</strong><br/>The schedule tells Xinc to check every 240 seconds for changes</li>
<li><strong>Line 05-07:</strong><br/>Modificationset monitors the project for changes, in this case a SVN workingcopy, and determines whether a new build needs to be triggered</li>
<li><strong>Line 08-10:</strong><br/>If a modification has been detected, the build scripts configured in the builders section are executed.<br/>In this case we have a <a href="http://phing.info" target="_new">Phing</a> builder calling the build.xml</li>
<li><strong>Line 11-20:</strong><br/>Independent of the build result, whether the build was successful or not a set of publishing tasks is executed.</li>
<li><strong>Line 12-15:</strong><br/>The onfailure task is only executed if the build failed, i.e. if the phingbuilder returned a failure.<br/>
The contained email task element will send a message about the failed build to a configured email address.</li>
<li><strong>Line 16-19:</strong><br/>The onsuccess task is only executed if the build is successful.<br/>
The contained email task element will send a message about the successful build to a configured email address.</li>


</ul>

<h4><a name="BuiltInProperties"></a>Built-in Properties</h4>

<p>Xinc provides access to pre-defined properties as if they had been
defined using a <em>&lt;property&gt;</em> task. See
<a href="appendixes/AppendixA-FactSheet.html#BuildInProperties">Appendix A</a>
for a complete list</p>

<h2><a name="OwnProject"></a>Setting up your own Project</h2>

<p>
For the configuration of your own projects,<br/>
please refer to:</p>
<ul>
<li><a href="appendixes/AppendixA-FactSheet.html">Appendix A: Fact Sheet</a></li>
<li><a href="appendixes/AppendixB-CoreTasks.html">Appendix B: Core Tasks</a></li>
<li><a href="appendixes/AppendixC-ModificationSet.html">Appendix C: ModificationSet</a></li>
<li><a href="appendixes/AppendixD-Builders.html">Appendix D: Builders</a></li>
<li><a href="appendixes/AppendixE-Publishers.html">Appendix E: Publishers</a></li>
</ul>
<p>
If you have open questions, please submit them in:</p>
<ul>
<li><a href="http://groups.google.com/group/xinc">Xinc Google Group</a></li>
<li><a href="http://xinc.googlecode.com">Google Code</a> as a bug-report / feature request</li>
</ul>

</body>
</html>
